home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / stdio / RCS / setbuf.man,v < prev    next >
Text File  |  1989-01-04  |  4KB  |  220 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     89.01.04.10.11.02;  author ouster;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     89.01.04.09.54.53;  author ouster;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @Added documentation for setvbuf.
  27. @
  28. text
  29. @.\" Copyright (c) 1980 Regents of the University of California.
  30. .\" All rights reserved.  The Berkeley software License Agreement
  31. .\" specifies the terms and conditions for redistribution.
  32. .\"
  33. .\"    @@(#)setbuf.3    6.3 (Berkeley) 10/16/87
  34. .\"
  35. .TH SETBUF 3S  "October 16, 1987"
  36. .UC 4
  37. .SH NAME
  38. setbuf, setbuffer, setlinebuf, setvbuf \- assign buffering to a stream
  39. .SH SYNOPSIS
  40. .B #include <stdio.h>
  41. .PP
  42. .B setbuf(stream, buf)
  43. .br
  44. .SM
  45. .B FILE
  46. .B *stream;
  47. .br
  48. .B char *buf;
  49. .PP
  50. .B setbuffer(stream, buf, size)
  51. .br
  52. .SM
  53. .B FILE
  54. .B *stream;
  55. .br
  56. .B char *buf;
  57. .br
  58. .B int size;
  59. .PP
  60. .B setlinebuf(stream)
  61. .br
  62. .SM
  63. .B FILE
  64. .B *stream;
  65. .PP
  66. \fBsetvbuf(stream, buf, mode, size)
  67. .br
  68. .SM
  69. FILE
  70. \fB*stream;
  71. .br
  72. \fBchar *buf;
  73. .br
  74. \fBint mode;
  75. .br
  76. \fBint size;\fR
  77.  
  78. .SH DESCRIPTION
  79. The three types of buffering available are unbuffered, block buffered,
  80. and line buffered.
  81. When an output stream is unbuffered, information appears on the
  82. destination file or terminal as soon as written;
  83. when it is block buffered many characters are saved up and written as a block;
  84. when it is line buffered characters are saved up until a newline is
  85. encountered or input is read from stdin.
  86. .I Fflush
  87. (see 
  88. .IR fclose (3S))
  89. may be used to force the block out early.
  90. Normally all files are block buffered.
  91. A buffer is obtained from
  92. .IR  malloc (3)
  93. upon the first
  94. .I getc
  95. or
  96. .IR  putc (3S)
  97. on the file.
  98. If the standard stream
  99. .B stdout
  100. refers to a terminal it is line buffered.
  101. The standard stream
  102. .B stderr
  103. is always unbuffered.
  104. .PP
  105. .I Setbuf
  106. is used after a stream has been opened but before it is read or written.
  107. The character array
  108. .I buf
  109. is used instead of an automatically allocated buffer.  If
  110. .I buf
  111. is the constant pointer
  112. .SM
  113. .B NULL,
  114. input/output will be completely unbuffered.
  115. A manifest constant 
  116. .SM
  117. .B BUFSIZ
  118. tells how big an array is needed:
  119. .IP
  120. .B char
  121. buf[BUFSIZ];
  122. .PP
  123. .IR Setbuffer ,
  124. an alternate form of 
  125. .IR setbuf ,
  126. is used after a stream has been opened but before it is read or written.
  127. The character array
  128. .I buf
  129. whose size is determined by the 
  130. .I size
  131. argument is used instead of an automatically allocated buffer.  If
  132. .I buf
  133. is the constant pointer
  134. .SM
  135. .BR NULL ,
  136. input/output will be completely unbuffered.
  137. .PP
  138. .I Setlinebuf
  139. is used to change
  140. .I stdout
  141. or
  142. .I stderr
  143. from block buffered or unbuffered to line buffered.
  144. Unlike
  145. .I setbuf
  146. and
  147. .I setbuffer
  148. it can be used at any time that the file descriptor is active.
  149. .PP
  150. \fISetvbuf\fR is the final form of \fIsetbuf\fR;  as with \fIsetbuf\fR,
  151. it must be invoked after a stream has been opened but before it is read
  152. or written.  The argument \fImode\fR determines how \fIstream\fR will
  153. be buffered:
  154. .SM
  155. \fB_IOFBF\fR
  156. causes input/output to be fully buffered,
  157. .SM
  158. \fB_IOLBF\fR
  159. causes output to be line buffered, and
  160. .SM
  161. \fB_IONBF\fR
  162. causes input/output to be unbuffered.  The argument \fIsize\fR specifies how
  163. large a buffer to use.  If \fIbuf\fR is 
  164. .SM
  165. \fBNULL\fR
  166. , then \fIsetvbuf\fR
  167. will allocate the buffer space;  otherwise, it will use the space at
  168. \fIbuf\fR (which must contain at least \fIsize\fR bytes).  \fISetvbuf\fR
  169. returns zero on success, or nonzero if an invalid value is given for
  170. \fImode\fR or if the request cannot be honored.
  171. .PP
  172. A file can be changed from unbuffered or line buffered to block buffered
  173. by using
  174. .I freopen
  175. (see
  176. .IR fopen (3S)).
  177. A file can be changed from block buffered or line buffered to unbuffered
  178. by using
  179. .I freopen
  180. followed by
  181. .I setbuf
  182. with a buffer argument of 
  183. .SM
  184. .BR NULL .
  185. .SH "SEE ALSO"
  186. fopen(3S),
  187. getc(3S),
  188. putc(3S),
  189. malloc(3),
  190. fclose(3S),
  191. puts(3S),
  192. printf(3S),
  193. fread(3S)
  194. .SH BUGS
  195. The
  196. .I setbuffer
  197. and
  198. .I setlinebuf
  199. functions are not portable to non-4.2BSD versions of UNIX.
  200. On 4.2BSD and 4.3BSD systems,
  201. .I setbuf
  202. always uses a suboptimal buffer size and should be avoided.
  203. .I Setbuffer
  204. is not usually needed
  205. as the default file I/O buffer sizes are optimal.
  206. @
  207.  
  208.  
  209. 1.1
  210. log
  211. @Initial revision
  212. @
  213. text
  214. @d10 1
  215. a10 1
  216. setbuf, setbuffer, setlinebuf \- assign buffering to a stream
  217. d37 13
  218. d121 22
  219. @
  220.